<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>&lt;GThread&gt;: </title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
<link rel="home" href="index.html" title="">
<link rel="up" href="ch01.html" title="GLib">
<link rel="prev" href="re65.html" title="&lt;%GLibTestSubprocessFlags&gt;">
<link rel="next" href="re67.html" title="&lt;%GLibThreadError&gt;">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="re65.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="re67.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="id-1.1.67"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>&lt;GThread&gt;</h2>
<p>&lt;GThread&gt;</p>
</div>
<div class="refsect1">
<a name="id-1.1.67.2"></a><h2>Description</h2>
<p>The <span class="type">GThread</span> struct represents a running thread. This struct
is returned by <code class="function">g_thread_new()</code> or <code class="function">g_thread_try_new()</code>. You can
obtain the <span class="type">GThread</span> struct representing the current thread by
calling <code class="function">g_thread_self()</code>.
</p>
<p>GThread is refcounted, see <code class="function">g_thread_ref()</code> and <code class="function">g_thread_unref()</code>.
The thread represented by it holds a reference while it is running,
and <code class="function">g_thread_join()</code> consumes the reference that it is given, so
it is normally not necessary to manage GThread references
explicitly.
</p>
<p>The structure is opaque -- none of its fields may be directly
accessed.</p>
</div>
<div class="refsect1">
<a name="id-1.1.67.3"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.67.3.2"></a><h3>join</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread:join self))
</pre></div>
<p>Waits until <em class="parameter"><code>thread</code></em> finishes, i.e. the function <em class="parameter"><code>func</code></em>, as
given to <code class="function">g_thread_new()</code>, returns or <code class="function">g_thread_exit()</code> is called.
If <em class="parameter"><code>thread</code></em> has already terminated, then <code class="function">g_thread_join()</code>
returns immediately.
</p>
<p>Any thread can wait for any other thread by calling <code class="function">g_thread_join()</code>,
not just its 'creator'. Calling <code class="function">g_thread_join()</code> from multiple threads
for the same <em class="parameter"><code>thread</code></em> leads to undefined behaviour.
</p>
<p>The value returned by <em class="parameter"><code>func</code></em> or given to <code class="function">g_thread_exit()</code> is
returned by this function.
</p>
<p><code class="function">g_thread_join()</code> consumes the reference to the passed-in <em class="parameter"><code>thread</code></em>.
This will usually cause the <span class="type">GThread</span> struct and associated resources
to be freed. Use <code class="function">g_thread_ref()</code> to obtain an extra reference if you
want to keep the GThread alive beyond the <code class="function">g_thread_join()</code> call.</p>
<div class="refsect3">
<a name="id-1.1.67.3.2.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>thread</p></td>
<td class="parameter_description">
<p>a <span class="type">GThread</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.67.3.3"></a><h3>ref</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread:ref self))
</pre></div>
<p>Increase the reference count on <em class="parameter"><code>thread</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.67.3.3.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>thread</p></td>
<td class="parameter_description">
<p>a <span class="type">GThread</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.67.3.4"></a><h3>unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (thread:unref self))
</pre></div>
<p>Decrease the reference count on <em class="parameter"><code>thread</code></em>, possibly freeing all
resources associated with it.
</p>
<p>Note that each thread holds a reference to its <span class="type">GThread</span> while
it is running, so it is safe to drop your own reference to it
if you don't need it anymore.</p>
<div class="refsect3">
<a name="id-1.1.67.3.4.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>thread</p></td>
<td class="parameter_description">
<p>a <span class="type">GThread</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.67.3.5"></a><h3>thread:try-new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread:try-new name func data))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.67.3.5.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>name</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">name</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.67.3.6"></a><h3>thread:new</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread:new name func data))
</pre></div>
<p>Undocumented</p>
<div class="refsect3">
<a name="id-1.1.67.3.6.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>name</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">name</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>func</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">func</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>data</p></td>
<td class="parameter_description">
<p></p>
<p>Passed as <code class="code">data</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.67.3.7"></a><h3>thread:error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread:error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.67.3.8"></a><h3>thread:exit</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (thread:exit retval))
</pre></div>
<p>Terminates the current thread.
</p>
<p>If another thread is waiting for us using <code class="function">g_thread_join()</code> then the
waiting thread will be woken up and get <em class="parameter"><code>retval</code></em> as the return value
of <code class="function">g_thread_join()</code>.
</p>
<p>Calling <code class="function">g_thread_exit()</code> with a parameter <em class="parameter"><code>retval</code></em> is equivalent to
returning <em class="parameter"><code>retval</code></em> from the function <em class="parameter"><code>func</code></em>, as given to <code class="function">g_thread_new()</code>.
</p>
<p>You must only call <code class="function">g_thread_exit()</code> from a thread that you created
yourself with <code class="function">g_thread_new()</code> or related APIs. You must not call
this function from a thread created with another threading library
or or from within a <span class="type">GThreadPool</span>.</p>
<div class="refsect3">
<a name="id-1.1.67.3.8.7"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>retval</p></td>
<td class="parameter_description">
<p>the return value of this thread</p>
<p>Passed as <code class="code">retval</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.67.3.9"></a><h3>thread:self</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (thread:self))
</pre></div>
<p>This function returns the <span class="type">GThread</span> corresponding to the
current thread. Note that this function does not increase
the reference count of the returned struct.
</p>
<p>This function will return a <span class="type">GThread</span> even for threads that
were not created by GLib (i.e. those created by other threading
APIs). This may be useful for thread identification purposes
(i.e. comparisons) but you must not use GLib functions (such
as <code class="function">g_thread_join()</code>) on these threads.</p>
</div>
<div class="refsect2">
<a name="id-1.1.67.3.10"></a><h3>thread:yield</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (thread:yield))
</pre></div>
<p>Causes the calling thread to voluntarily relinquish the CPU, so
that other threads can run.
</p>
<p>This function is often used as a method to make busy wait less evil.</p>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>
